/*            Copyright(c) 2006-2008 Dave Sexton           *
 * http://www.codeplex.com/DocProject                      *
 * http://www.codeplex.com/DocProject/Project/License.aspx *
 ***********************************************************/
using System;
using System.Collections.Generic;
using System.Text;
using VSLangProj80;

namespace DaveSexton.DocProject.Engine
{
	public enum BuildType
	{
		// NOTE: The SetBuildTypeWithPrecedence method implementation of the BuildEngine class requires that the following constants are 
		// defined in ascending numeric order of increasing precedence: 

		Default, 
		Skip, 
		Partial,
		Full
	}

	public interface IBuildEngine : IDisposable
	{
		/// <summary>
		/// Gets the settings for the <see cref="Build" /> process.
		/// </summary>
		BuildSettings Settings { get; }

		/// <summary>
		/// Gets the <see cref="Project" /> options for the <see cref="Build" /> process.
		/// </summary>
		DocProjectOptions Options { get; }

		/// <summary>
		/// Gets the <see cref="IDocProject" /> instance for which the engine will <see cref="Build" /> compiled help.
		/// </summary>
		IDocProject Project { get; }

		/// <summary>
		/// Gets or sets whether the engine should perform a full or partial build, skip building completely or determine the appropriate action 
		/// based on the presence of certain files and their timestamps.
		/// </summary>
		BuildType BuildType { get; set; }

		/// <summary>
		/// When implemented, gets a collection of files and folders that may be included as project items or automatically removed by 
		/// the engine during a <see cref="Clean" /> operation.  The items can also have other meaning that is special to 
		/// the engine in some way.
		/// </summary>
		/// <remarks>
		/// A null reference or empty list are acceptable return values.
		/// </remarks>
		DocProjectItemCollection BuildItems { get; }

		DateTime LastBuild { get; }

		/// <summary>
		/// Gets the collection of steps for the <see cref="Build" /> process.
		/// </summary>
		BuildStepCollection Steps { get; }

		/// <summary>
		/// Performs the build sequence of the current <see cref="BuildType" /> for the <see cref="Project" /> using the current 
		/// <see cref="Settings" /> and <see cref="Project" /> <see cref="Options" />.
		/// </summary>
		void Build(BuildContext context);

		/// <summary>
		/// Performs the build sequence of the current <see cref="BuildType" /> for the <see cref="Project" /> using the current 
		/// <see cref="Settings" /> and <see cref="Project" /> <see cref="Options" />.
		/// </summary>
		bool Build();

		void Clean(BuildContext context);

		bool Clean();

		void Cancel();

		void Refresh();

		/// <returns><strong>true</strong> if one or more special files or folders have been included as project items; otherwise, <strong>false</strong>.</returns>
		bool IncludeBuildItems();

		void SetBuildTypeWithPrecedence(BuildType type);
	}
}
